Inside Macintosh: QuickTime

Previous | Chapter Top | Chapter Contents | Next

CompressSequenceBegin

Your application calls the CompressSequenceBegin function to signal the beginning of the process of compressing a sequence of frames. The Image Compression Manager prepares for the sequence-compression operation by reserving appropriate system resources. You must call this function before calling the CompressSequenceFrame function, which is described in the next section.

pascal OSErr CompressSequenceBegin (ImageSequence *seqID,
                                         PixMapHandle src,
                                         PixMapHandle prev,
                                         const Rect *srcRect,
                                         const Rect *prevRect,
                                         short colorDepth,
                                         CodecType cType,
                                         CompressorComponent codec,
                                         CodecQ spatialQuality,
                                         CodecQ temporalQuality,
                                         long keyFrameRate,
                                         CTabHandle ctable,
                                         CodecFlags flags,
                                         ImageDescriptionHandle desc);


seqID

Contains a pointer to a field to receive the unique identifier for this sequence. You must supply this identifier to all subsequent Image Compression Manager functions that relate to this sequence.

src

Contains a handle to a pixel map that will contain the image to be compressed. The image must be stored in a pixel map structure.

prev

Contains a handle to a pixel map that will contain a previous image. The compressor uses this buffer to store a previous image against which the current image (stored in the pixel map referred to by the src parameter) is compared when performing temporal compression. This pixel map must be created at the same depth and with the same color table as the source image. The compressor manages the contents of this pixel map based upon several considerations, such as the key frame rate and the degree of difference between compared images. If you want the compressor to allocate this pixel map or if you do not want to perform temporal compression (that is, you have set the value of the temporalQuality parameter to 0), set this parameter to nil .

You can set or change the previous image buffer for an active sequence by calling the SetCSequencePrev function. You can obtain a pointer to a pixel map that was allocated by the compressor by calling the GetCSequencePrevBuffer function. See "Changing Sequence-Compression Parameters," which begins on Changing Sequence-Compression Parameters , for information about these functions.

srcRect

Contains a pointer to a rectangle defining the portion of the image to compress. The compressor applies this rectangle to the image stored in the buffer referred to by the src parameter.

prevRect

Contains a pointer to a rectangle defining the portion of the previous image to use for temporal compression. The compressor uses this portion of the previous image as the basis of comparison with the current image. The compressor ignores this parameter if you have not provided a buffer for previous images. This rectangle must be the same size as the source rectangle, which is specified with the srcRect parameter.

You can set or change the rectangle used with the previous image buffer for an active sequence by calling the SetCSequencePrev function. See "Changing Sequence-Compression Parameters," which begins on Changing Sequence-Compression Parameters , for information about this function.

colorDepth

Specifies the depth at which the sequence is likely to be viewed. Compressors may use this as an indication of the color or grayscale resolution of the compressed images. If you set this parameter to 0, the Image Compression Manager determines the appropriate value for the source image. Values of 1, 2, 4, 8, 16, 24, and 32 indicate the number of bits per pixel for color images. Values of 34, 36, and 40 indicate 2-bit, 4-bit, and 8-bit grayscale, respectively, for grayscale images. Your program can determine which depths are supported by a given compressor by examining the compressor information structure returned by the GetCodecInfo function (described on GetCodecInfo ).

cType

Specifies a compressor type. You must set this parameter to a valid compressor type (see Table 3 for a list of the available compressor types).

codec

Specifies a compressor identifier. Specify a particular compressor by setting this parameter to its compressor identifier. Alternatively, you may use one of the special identifiers:

anyCodec

Choose the first compressor of the specified type

bestSpeedCodec

Choose the fastest compressor of the specified type

bestFidelityCodec

Choose the most accurate compressor of the specified type

bestCompressionCodec

Choose the compressor that produces the smallest resulting data

You can also specify a component instance. This may be useful if you have previously set some parameter on a specific instance of a codec field and want to make sure that the specified instance is used for that operation.

If you set the codec parameter to anyCodec , the Image Compression Manager chooses the first compressor it finds of the specified type.

spatialQuality

Specifies the desired compressed image quality. See "Compression Quality Constants," for available values. You can change the value of this parameter for an active sequence by calling the SetCSequenceQuality function (described on SetCSequenceQuality ).

temporalQuality

Specifies the desired sequence temporal quality. This parameter governs the level of compression you desire with respect to information between successive frames in the sequence. Set this parameter to 0 to prevent the compressor from applying temporal compression to the sequence. See "Compression Quality Constants," for other available values.

You can change the value of this parameter for an active sequence by calling the SetCSequenceQuality function (described on SetCSequenceQuality ).

keyFrameRate

Specifies the maximum number of frames allowed between key frames. Key frames provide points from which a temporally compressed sequence may be decompressed. Use this parameter to control the frequency at which the compressor places key frames into the compressed sequence. The compressor determines the optimum placement for key frames based upon the amount of redundancy between adjacent images in the sequence. Consequently, the compressor may insert key frames more frequently than you have requested. However, the compressor never places fewer key frames than is indicated by the setting of the keyFrameRate parameter. The compressor ignores this parameter if you have not requested temporal compression (that is, you have set the temporalQuality parameter to 0). If you pass in 0 in this parameter, this indicates that there are no key frames in the sequence. If you pass in any other number , it specifies the number of non-key frames between key frames. Set this parameter to 1 to specify all key frames, to 2 to specify every other frame as a key frame, to 3 to specify every third frame as a key frame, and so forth.

Your application may change the key frame rate for an active sequence by calling the SetCSequenceKeyFrameRate function (described beginning on SetCSequenceKeyFrameRate ). See "Defining Key Frame Rates" for more information about key frames.

ctable

Contains a handle to a custom color lookup table. Your program may use this parameter to indicate a custom color lookup table to be used with this image. If the value of the colorDepth parameter is less than or equal to 8 and the custom color lookup table is different from that of the source pixel map (that is, the ctSeed field values differ in the two pixel maps), the compressor remaps the colors of the image to the custom colors. If you set the colorDepth parameter to 16, 24, or 32, the compressor stores the custom color table with the compressed image. The compressor may use the table to specify the best colors to use when displaying the image at lower bit depths. The compressor ignores the ctable parameter when colorDepth is set to 33, 34, 36, or 40. If you set this parameter to nil , the compressor uses the color lookup table from the source pixel map.

flags

Contains flags providing further control information. See "Image Compression Manager Function Control Flags," which begins on Image Compression Manager Function Control Flags , for information about CodecFlags fields. You must set either the value of the codecFlagUpdatePrevious flag or the codecFlagUpdatePreviousComp flag to 1 (be sure to set unused flags to 0). The following flags are available for this function:

codecFlagUpdatePrevious

Controls whether the compressor updates the previous image during compression. This flag is only used with sequences that are being temporally compressed. If you set this flag to 1, the compressor copies the current frame into the previous frame buffer at the end of frame compression.

codecFlagUpdatePreviousComp

Controls whether the compressor updates the previous image buffer with the compressed image. This flag is only used with temporal compression and is similar to the codecFlagUpdatePrevious flag. As with the codecFlagUpdatePrevious flag, if you set this flag to 1, the compressor updates the previous frame buffer at the end of frame compression. However, this flag causes the Image Compression Manager to update the frame buffer using an image obtained by decompressing the results of the most recent compression operation, rather than the source image, which may give better results at the expense of taking more time.

codecFlagWasCompressed

Indicates to the compressor that the image to be compressed has been compressed before. This information may be useful to compressors that can compensate for the image degradation that may otherwise result from repeated compression and decompression of the same image. Set this flag to 1 to indicate that the image was previously compressed. Set this flag to 0 if the image was not previously compressed.

desc

Contains a handle that is to receive a formatted image description structure. The Image Compression Manager resizes this handle for the returned image description structure. Your application should store this image description with the compressed sequence. During the compression operation, the Image Compression Manager and the compressor component update the contents of this image description. Consequently, you should not store the image description until the sequence has been completely processed.

CompressSequenceFrame

Your application calls the CompressSequenceFrame function to compress one of a sequence of frames.

pascal OSErr CompressSequenceFrame (ImageSequence seqID,
                                         PixMapHandle src, const Rect *srcRect,
                                         CodecFlags flags, Ptr data, long *dataSize,
                                         UInt8 *similarity,
                                         ICMCompletionProcRecordPtr asyncCompletionProc);


seqID

Unique sequence identifier that was returned by the CompressSequenceBegin function (described in the previous section).

src

Contains a handle to a pixel map that contains the image to be compressed. The image must be stored in a pixel map structure.

srcRect

Contains a pointer to a rectangle defining the portion of the image to compress. The compressor applies this rectangle to the image stored in the buffer referred to by the src parameter.

flags

Specifies flags providing further control information. See "Image Compression Manager Function Control Flags," which begins on Image Compression Manager Function Control Flags , for information about CodecFlags fields. You must set the value of either the codecFlagUpdatePrevious flag or the codecFlagUpdatePreviousComp flag to 1 (be sure to set unused flags to 0). The following flags are available for this function:

codecFlagUpdatePrevious

Controls whether the compressor updates the previous image during compression. This flag is only used with sequences that are being temporally compressed. If you set this flag to 1, the compressor copies the current frame into the previous frame buffer at the end of frame compression.

Indicates to the compressor that the image to be compressed has been compressed before. This information may be useful to compressors that can compensate for the image degradation that may otherwise result from repeated compression and decompression of the same image. Set this flag to 1 to indicate that the image was previously compressed. Set this flag to 0 if the image was not previously compressed.

codecFlagUpdatePreviousComp

Controls whether the compressor updates the previous image buffer with the compressed image. This flag is only used with temporal compression and is similar to the codecFlagUpdatePrevious flag. As with the codecFlagUpdatePrevious flag, if you set this flag to 1, the compressor updates the previous frame buffer at the end of frame compression. However, this flag causes the Image Compression Manager to update the frame buffer using an image obtained by decompressing the results of the most recent compression operation, rather than the source image.

codecFlagForceKeyFrame

Controls whether the compressor creates a key frame from the current image. This flag is only used with temporal compression. If you set this flag to 1, the compressor makes the current image a key frame. If you set this flag to 0, the compressor decides based on other criteria, such as the key frame rate, whether to create a key frame from the current image. If you don't want any key frames other than the ones that are forced, set the key frame rate for the sequence to 0.

codecFlagLiveGrab

Indicates to the compressor that speed is of the utmost importance, and that size and quality are of lesser importance. This flag is useful when you are grabbing sequences from a live source where each frame must be compressed quickly.

data

Points to a location to receive the compressed image data. It is your program's responsibility to make sure that this location can receive at least as much data as indicated by the GetMaxCompressionSize function (described on GetMaxCompressionSize ). The Image Compression Manager places the actual size of the compressed image into the field referred to by the dataSize parameter. This pointer must contain a 32-bit clean address. If you use a dereferenced, locked handle, you must call the Memory Manager's StripAddress routine before you use that pointer with this parameter. For details on StripAddress , see Inside Macintosh: Memory .

dataSize

Contains a pointer to a field that is to receive the size, in bytes, of the compressed image.

similarity

Contains a pointer to a field that is to receive a similarity value. The CompressSequenceFrame function returns a value that indicates the similarity of the current frame to the previous frame. A value of 0 indicates that the current frame is a key frame in the sequence. A value of 255 indicates that the current frame is identical to the previous frame. Values from 1 through 254 indicate relative similarity, ranging from very different (1) to very similar (254).

asyncCompletionProc

Points to a completion function structure. The compressor calls your completion function when an asynchronous compression operation is complete. You can cause the compression to be performed asynchronously by specifying a completion function if the compressor supports asynchronous compression. For more information about completion function structures, see "Completion Functions" .

If you specify asynchronous operation, you must not read the compressed data until the compressor indicates that the operation is complete by calling your completion function. Set asyncCompletionProc to nil to specify synchronous compression. If you set asyncCompletionProc to -1, the operation is performed asynchronously but the compressor does not call your completion function.

If the asyncCompletionProc parameter is not nil , the following conditions are in effect: the pixels in the source image must stay valid until the completion function is called with its codecCompletionSource flag, and the resulting compressed data is not valid until it is called with its codecCompletionDest flag set.

DecompressSequenceBegin

The Movie Toolbox handles the details of decompressing image sequences in QuickTime movies. If you need to decompress other sequences, your application calls this function to signal the beginning of the process of decompressing a sequence of frames. You must call this function before calling the DecompressSequenceFrame function (described in the next section).

pascal OSErr DecompressSequenceBegin (ImageSequence *seqID,
                                         ImageDescriptionHandle desc,
                                         CGrafPtr port, GDHandle gdh,
                                         const Rect *srcRect,
                                         MatrixRecordPtr matrix, short mode,
                                         RgnHandle mask, CodecFlags flags,
                                         CodecQ accuracy,
                                         DecompressorComponent codec);


seqID

Contains a pointer to a field to receive the unique identifier for this sequence returned by the CompressSequenceBegin function (described on CompressSequenceBegin ). You must supply this identifier to all subsequent Image Compression Manager functions that relate to this sequence.

desc

Contains a handle to the image description structure that describes the compressed image.

port

Points to the graphics port for the destination image. If this parameter specifies a graphics world or points to the screen, set the gdh parameter to nil . If you set this parameter to nil , the Image Compression Manager uses the current port (in this case, you should also set the gdh parameter to nil ).

gdh

Contains a handle to the graphics device record for the destination image. If the port parameter specifies a graphics world or the screen, or if you set the port parameter to nil , set this parameter to nil .

srcRect

Contains a pointer to a rectangle defining the portion of the image to decompress. This rectangle must lie within the boundary rectangle of the compressed image, which is defined by (0,0) and ((**desc).width,(**desc).height) . If you want to decompress the entire source image, set this parameter to nil . If the srcRect parameter is nil , the rectangle is set to the rectangle structure of the image description structure. Your application can change the source rectangle for an active sequence by calling the SetDSequenceSrcRect function (described on SetDSequenceSrcRect ).

matrix

Points to a matrix structure that specifies how to transform the image during decompression. You can use the matrix structure to translate or scale the image during decompression. If you do not want to apply such effects, set the matrix parameter to nil . For more information about matrix operations, see the chapter "Movie Toolbox" in this book.

Your application can change the matrix for an active sequence by calling the SetDSequenceMatrix function (described on SetDSequenceMatrix ).

mode

Specifies the transfer mode for the operation. The Image Compression Manager supports the same transfer modes supported by QuickDraw's CopyBits routine (described in Inside Macintosh: Imaging ).

Your application can change the transfer mode for an active sequence by calling the SetDSequenceTransferMode function (described on SetDSequenceTransferMode ).

mask

Contains a handle to a clipping region in the destination coordinate system. If specified, the decompressor applies this mask to the destination image. If you do not want to mask pixels in the destination, set this parameter to nil .

Your application can change the clipping mask for an active sequence by calling the SetDSequenceMask function (described on SetDSequenceMask ).

flags

Contains flags providing further control information. See "Image Compression Manager Function Control Flags," which begins on Image Compression Manager Function Control Flags , for information about CodecFlags fields. The following flags are available for this function:

codecFlagUseScreenBuffer

Controls whether the decompressor allocates an offscreen buffer. The decompressor places the decompressed image into that buffer and then copies the image to the destination pixel map after completing the decompression operation. Using an offscreen buffer reduces the tearing effect that can result from writing directly to the screen during decompression. Set this flag to 1 to cause the decompressor to allocate and use an offscreen buffer. Set this flag to 0 to cause the decompressor to write to the destination pixel map.

Your application can determine the screen buffer for an active sequence by calling the GetDSequenceScreenBuffer function (described on GetDSequenceScreenBuffer ).

codecFlagUseImageBuffer

Controls whether the decompressor allocates an offscreen buffer for the current image. The decompressor uses this buffer to store the compressed data from the current image so that subsequent images that are temporally compressed can be processed correctly. Set this flag to 1 to cause the decompressor to use an image buffer. Set this flag to 0 if your sequence is not temporally compressed and therefore does not require the use of an image buffer.

Your application can determine the image buffer for an active sequence by calling the GetDSequenceImageBuffer function (described on GetDSequenceImageBuffer ).

accuracy

Specifies the accuracy desired in the decompressed image. Values for this parameter are on the same scale as compression quality. See  "Compression Quality Constants," for available values.

Your application can change the accuracy parameter for an active sequence by calling the SetDSequenceAccuracy function (described on SetDSequenceAccuracy ).

codec

Contains a compressor identifier. Specify a particular decompressor by setting this parameter to its compressor identifier. Alternatively, you may use one of the special identifiers:

anyCodec

Choose the first decompressor of the specified type

bestSpeedCodec

Choose the fastest decompressor of the specified type

bestFidelityCodec

Choose the most accurate decompressor of the specified type

You can also specify a component instance. This may be useful if you have previously set some parameter on a specific instance of a codec field and want to make sure that the specified instance is used for that operation.

If you set the codec parameter to anycodec , the Image Compression Manager chooses the first decompressor it finds of the specified type.

DecompressSequenceFrame

Your application calls the DecompressSequenceFrame function to decompress one of a sequence of frames. You must have called the DecompressSequenceBegin function before calling this function. You specify the destination with the port parameter to the DecompressSequenceBegin function, described in the previous section.

pascal OSErr DecompressSequenceFrame (ImageSequence seqID,
                                         Ptr data, CodecFlags inFlags,
                                         CodecFlags *outFlags,
                                         ICMCompletionProcRecordPtr asyncCompletionProc);


seqID

Contains the unique sequence identifier that was returned by the DecompressSequenceBegin function (described on DecompressSequenceBegin ).

data

Points to the compressed image data. This pointer must contain a 32-bit clean address. If you use a dereferenced, locked handle, you must call the Memory Manager's StripAddress routine before you use that pointer with this parameter.

inFlags

Contains flags providing further control information. See "Image Compression Manager Function Control Flags," which begins on Image Compression Manager Function Control Flags , for information about CodecFlags fields. The following flags are available for this function:

codecFlagNoScreenUpdate

Controls whether the decompressor updates the screen image. If you set this flag to 1, the decompressor does not write the current frame to the screen, but does write the frame to its offscreen image buffer (if one was allocated). If you set this flag to 0, the decompressor writes the frame to the screen.

codecFlagDontOffscreen

Controls whether the decompressor uses the offscreen buffer during sequence decompression. This flag is only used with sequences that have been temporally compressed. If this flag is set to 1, the decompressor does not use the offscreen buffer during decompression. Instead, the decompressor returns an error. This allows your application to refill the offscreen buffer. If this flag is set to 0, the decompressor uses the offscreen buffer if appropriate.

codecFlagOnlyScreenUpdate

Controls whether the decompressor decompresses the current frame. If you set this flag to 1, the decompressor writes the contents of its offscreen image buffer to the screen, but does decompress the current frame. If you set this flag to 0, the decompressor decompresses the current frame and writes it to the screen. You can set this flag to 1 only if you have allocated an offscreen image buffer for use by the decompressor.

outFlags

Contains a pointer to status flags. The decompressor updates these flags at the end of the decompression operation. See "Image Compression Manager Function Control Flags," which begins on Image Compression Manager Function Control Flags , for information about CodecFlags constants. The following flags may be set by this function:

codecFlagUsedNewImageBuffer

Indicates to your application that the decompressor used the offscreen image buffer for the first time when it processed this frame. If this flag is set to 1, the decompressor used the image buffer for this frame and this is the first time the decompressor used the image buffer in this sequence.

codecFlagUsedImageBuffer

Indicates whether the decompressor used the offscreen image buffer. If the decompressor used the image buffer during the decompress operation, it sets this flag to 1. Otherwise, it sets this flag to 0.

codecFlagDontUseNewImageBuffer

Forces an error to be returned when a new image buffer would have to be allocated instead of allocating the new buffer.

codecFlagInterlaceUpdate

Updates the screen by interlacing even and odd scan lines to reduce tearing artifacts (if the decompressor supports this mode).

asyncCompletionProc

Points to a completion function structure. The compressor calls your completion function when an asynchronous decompression operation is complete. You can cause the decompression to be performed asynchronously by specifying a completion function. See "Completion Functions," which begins on Completion Functions , for more information about completion functions.

If you specify asynchronous operation, you must not read the decompressed image until the decompressor indicates that the operation is complete by calling your completion function. Set asyncCompletionProc to nil to specify synchronous decompression. If you set asyncCompletionProc to -1, the operation is performed asynchronously but the decompressor does not call your completion function.

CDSequenceBusy

Your application may call the CDSequenceBusy function to check the status of an asynchronous compression or decompression operation .

pascal OSErr CDSequenceBusy (ImageSequence seqID);


seqID

Contains the unique sequence identifier that was returned by the DecompressSequenceBegin or CompressSequenceBegin function (described on DecompressSequenceBegin and CompressSequenceBegin , respectively).

CDSequenceEnd

Your application calls the CDSequenceEnd function to indicate the end of processing for an image sequence.

pascal OSErr CDSequenceEnd (ImageSequence seqID);


seqID

Contains the unique sequence identifier that was returned by the DecompressSequenceBegin or CompressSequenceBegin function (described on DecompressSequenceBegin and CompressSequenceBegin , respectively).